* gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c: Documentation updates.
* gtk/tmpl/gtkdnd.sgml, gtk/tmpl/gtkclipboard.sgml,
gdk/tmpl/general.sgml, gdk/tmpl/threads.sgml,
gdk/tmpl/x_interaction.sgml: Updates.
+2001-10-17 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+ Documentation updates.
+
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
+2001-10-17 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+ Documentation updates.
+
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
+2001-10-17 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+ Documentation updates.
+
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
+2001-10-17 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+ Documentation updates.
+
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
+2001-10-17 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+ Documentation updates.
+
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
+2001-10-17 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+ Documentation updates.
+
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
+2001-10-17 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/gtkdnd.c, gtk/gtkclipboard.c, gdk/x11/gdkmain-x11.c:
+ Documentation updates.
+
Wed Oct 17 15:17:20 2001 Owen Taylor <otaylor@redhat.com>
* gtk/gtkentry.c (gtk_entry_real_insert_text): Fix mistake
+2001-10-17 Matthias Clasen <matthiasc@poet.de>
+
+ * gtk/tmpl/gtkdnd.sgml, gtk/tmpl/gtkclipboard.sgml,
+ gdk/tmpl/general.sgml, gdk/tmpl/threads.sgml,
+ gdk/tmpl/x_interaction.sgml: Updates.
+
2001-10-13 Matthias Clasen <matthiasc@poet.de>
* gdk/tmpl/x_interaction.sgml: Update.
<!-- ##### MACRO GDK_WINDOWING_X11 ##### -->
<para>
-
+This macro is defined if GDK is configured to use the X backend.
</para>
<!-- ##### MACRO GDK_WINDOWING_WIN32 ##### -->
<para>
-
+This macro is defined if GDK is configured to use the Win32 backend.
</para>
<!-- ##### MACRO GDK_WINDOWING_FB ##### -->
<para>
-
+This macro is defined if GDK is configured to use the Linux framebuffer backend.
</para>
Threads
<!-- ##### SECTION Short_Description ##### -->
-
+functions for using GDK in multi-threaded programs
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+For thread safety, GDK relies on the thread primitives in GLib,
+and on the thread-safe GLib main loop.
+</para>
+<para>
+You must call g_thread_init() before executing any other GTK+ or GDK
+functions in a threaded GTK+ program.
+</para>
+<para>
+Idles, timeouts, and input functions are executed outside
+of the main GTK+ lock. So, if you need to call GTK+
+inside of such a callback, you must surround the callback
+with a gdk_threads_enter()/gdk_threads_leave() pair.
+(However, signals are still executed within the main
+GTK+ lock.)
+</para>
+<para>
+In particular, this means, if you are writing widgets that might
+be used in threaded programs, you <emphasis>must</emphasis> surround
+timeouts and idle functions in this matter.
+</para>
+<para>
+As always, you must also surround any calls to GTK+ not made within
+a signal handler with a gdk_threads_enter()/gdk_threads_leave() pair.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### MACRO GDK_THREADS_ENTER ##### -->
<para>
-
+This macro marks the begin of a critical section
+in which GDK and GTK+ functions can be called.
+Only one thread at a time can be in such a critial
+section.
</para>
<!-- ##### MACRO GDK_THREADS_LEAVE ##### -->
<para>
-
+This macro marks the end of a critical section
+begun with #GDK_THREADS_ENTER.
</para>
<!-- ##### FUNCTION gdk_threads_enter ##### -->
<para>
-
+Enters a critical region like #GDK_THREADS_ENTER.
</para>
<!-- ##### FUNCTION gdk_threads_leave ##### -->
<para>
-
+Leaves a critical region begun with gdk_threads_enter().
</para>
<!-- ##### VARIABLE gdk_threads_mutex ##### -->
<para>
-
+The #GMutex used to implement the critical region for
+gdk_threads_enter()/gdk_threads_leave().
</para>
<!-- ##### FUNCTION gdk_x11_gc_get_xdisplay ##### -->
<para>
-
+Returns the display of a #GdkGC.
</para>
-@gc:
-@Returns:
+@gc: a #GdkGC.
+@Returns: an Xlib <type>Display*</type>.
<!-- ##### FUNCTION gdk_x11_gc_get_xgc ##### -->
<para>
-
+Returns the X GC of a #GdkGC.
</para>
-@gc:
-@Returns:
+@gc: a #GdkGC.
+@Returns: an Xlib <type>GC</type>.
<!-- ##### FUNCTION gdk_x11_get_default_root_xwindow ##### -->
<para>
-
+Gets the root window of the default screen
+(see gdk_x11_get_default_screen()).
</para>
-@Returns:
+@Returns: an Xlib <type>Window</type>.
<!-- ##### FUNCTION gdk_x11_get_default_screen ##### -->
<!-- ##### FUNCTION gdk_x11_get_default_xdisplay ##### -->
<para>
-
+Gets the default GTK+ display.
</para>
-@Returns:
+@Returns: the Xlib <type>Display*</type> for the display
+ specified in the <option>--display</option> command line option
+ or the <envar>DISPLAY</envar> environment variable.
<!-- ##### FUNCTION gdk_x11_grab_server ##### -->
<!-- ##### FUNCTION gdk_x11_image_get_xdisplay ##### -->
<para>
-
+Returns the display of a #GdkImage.
</para>
-@image:
-@Returns:
+@drawable: a #GdkImage.
+@Returns: an Xlib <type>Display*</type>.
<!-- ##### FUNCTION gdk_x11_image_get_ximage ##### -->
<!-- ##### USER_FUNCTION GtkClipboardReceivedFunc ##### -->
<para>
- A function to be called when the results of gtk_clipboard_request_text()
+ A function to be called when the results of gtk_clipboard_request_contents()
are received, or when the request fails.
</para>
A function that will be called to provide the contents of the selection.
If multiple types of data were advertised, the requested type can
be determined from the @info parameter or by checking the target field
-of @selection_data. If the data could succesfully be converted into
+of @selection_data. If the data could successfully be converted into
then it should be stored into the @selection_data object by
calling gtk_selection_data_set() (or related functions such
-as gtk_seletion_data_get().) If no data is set, the requestor
+as gtk_selection_data_set_text()). If no data is set, the requestor
will be informed that the attempt to get the data failed.
</para>
<!-- ##### SECTION Long_Description ##### -->
<para>
GTK+ has a rich set of functions for doing inter-process
-communication via the drag-and-drop metaphore. GTK+
-can do drag and drop (DND) via multiple protocols.
+communication via the drag-and-drop metaphor. GTK+
+can do drag-and-drop (DND) via multiple protocols.
The currently supported protocols are the Xdnd and
Motif protocols.
<entry>
If set for a widget, GTK+ will draw a highlight on
this widget as long as a drag is over this widget
- and the wiget drag format and action is accetable.</entry>
+ and the widget drag format and action are acceptable.</entry>
</row>
<row>
will check if the drag matches this widget's
list of possible targets and actions. If so,
GTK+ will call gtk_drag_data_get() on behalf
- of the widget. Whether or not the drop is succesful,
+ of the widget. Whether or not the drop is successful,
GTK+ will call gtk_drag_finish(). If the action
- was a move, then if the drag was succesful, then
+ was a move, then if the drag was successful, then
%TRUE will be passed for the @delete parameter
to gtk_drag_finish().
</entry>
<!-- ##### ENUM GtkTargetFlags ##### -->
<para>
-The #GtkTargetFlags enumeration is used to specifies
-constraints on an entry in a GtkTargetTable.
+The #GtkTargetFlags enumeration is used to specify
+constraints on an entry in a #GtkTargetTable.
</para>
<variablelist>
<varlistentry><term> %GTK_TARGET_SAME_APP </term>
<!-- ##### FUNCTION gtk_drag_dest_set ##### -->
<para>
-Set a widget as a potential drop destination.
+Sets a widget as a potential drop destination.
</para>
-@widget: a widget
+@widget: a #GtkWidget
@flags: the flags that specify what actions GTK+ should take
on behalf of a widget for drops onto that widget. The @targets
and @actions fields only are used if %GTK_DEST_DEFAULT_MOTION
<!-- ##### FUNCTION gtk_drag_dest_set_proxy ##### -->
<para>
-Set this widget as a proxy for drops to another window.
+Sets this widget as a proxy for drops to another window.
</para>
@widget: a #GtkWidget
@protocol: the drag protocol which the @proxy_window accepts
(You can use gdk_drag_get_protocol() to determine this)
@use_coordinates: If true, send the same coordinates to the
- destination, because it is a embedded
+ destination, because it is an embedded
subwindow.
<!-- ##### FUNCTION gtk_drag_dest_unset ##### -->
<para>
-Clear information about a drop destination set with
+Clears information about a drop destination set with
gtk_drag_dest_set(). The widget will no longer receive
notification of drags.
</para>
<!-- ##### FUNCTION gtk_drag_finish ##### -->
<para>
-Inform the drag source that the drop is finished, and
+Informs the drag source that the drop is finished, and
that the data of the drag will no longer be required.
</para>
@context: the drag context.
-@success: a flag indicating whether the drop was succesful
+@success: a flag indicating whether the drop was successful
@del: a flag indicating whether the source should delete the
original data. (This should be %TRUE for a move)
@time: the timestamp from the "drag_data_drop" signal.
<!-- ##### FUNCTION gtk_drag_get_source_widget ##### -->
<para>
-Determine the source widget for a drag.
+Determines the source widget for a drag.
</para>
@context: a (destination side) drag context.
@Returns: if the drag is occurring within a single application,
- a pointer to the source widget. Otherwise, NULL.
+ a pointer to the source widget. Otherwise, %NULL.
<!-- ##### FUNCTION gtk_drag_highlight ##### -->
<para>
-Draw a highlight around a widget. This will attach
+Draws a highlight around a widget. This will attach
handlers to "expose_event" and "draw", so the highlight
-will continue to be displayed until gtk_drag_unhighlight
+will continue to be displayed until gtk_drag_unhighlight()
is called.
</para>
<!-- ##### FUNCTION gtk_drag_unhighlight ##### -->
<para>
-Remove a highlight set by gtk_drag_highlight() from
+Removes a highlight set by gtk_drag_highlight() from
a widget.
-is called.
</para>
@widget: a widget to remove the highlight from.
<!-- ##### FUNCTION gtk_drag_begin ##### -->
<para>
-Initiate a drag on the source side. The function
+Initiates a drag on the source side. The function
only needs to be used when the application is
starting drags itself, and is not needed when
gtk_drag_source_set() is used.
drag.
@button: The button the user clicked to start the drag.
@event: The event that triggered the start of the
- drag. Usually
+ drag.
@Returns: The context for this drag.
<!-- ##### FUNCTION gtk_drag_source_unset ##### -->
<para>
-Undo the effects of gtk_drag_source_set().
+Undoes the effects of gtk_drag_source_set().
</para>
@widget: a #GtkWidget
/**
* gtk_clipboard_get:
* @selection: a #GdkAtom which identifies the clipboard
- * to use. A value of GDK_NONE here is the
+ * to use. A value of %GDK_NONE here is the
* same as gdk_atom_intern ("CLIPBOARD", FALSE),
* and provides the default clipboard. Another
- * common value is GDK_SELECTION_PRIMARY, which
+ * common value is %GDK_SELECTION_PRIMARY, which
* identifies the primary X selection.
*
* Returns the clipboard object for the given selection.
* Return value: the appropriate clipboard object. If no
* clipboard already exists, a new one will
* be created. Once a clipboard object has
- * been created, it is persistant for all time.
+ * been created, it is persistent for all time.
**/
GtkClipboard *
gtk_clipboard_get (GdkAtom selection)
* @n_targets: number of elements in @targets
* @get_func: function to call to get the actual clipboard data
* @clear_func: when the clipboard contents are set again, this function will
- * be called, and get_func will not be subsequently called.
+ * be called, and @get_func will not be subsequently called.
* @user_data: user data to pass to @get_func and @clear_func.
*
- * Virtually set the contents of the specified clipboard by providing
+ * Virtually sets the contents of the specified clipboard by providing
* a list of supported formats for the clipboard data and a function
* to call to get the actual data when it is requested.
*
* @n_targets: number of elements in @targets
* @get_func: function to call to get the actual clipboard data
* @clear_func: when the clipboard contents are set again, this function will
- * be called, and get_func will not be subsequently called.
+ * be called, and @get_func will not be subsequently called.
* @owner: an object that "owns" the data. This object will be passed
* to the callbacks when called.
*
- * Virtually set the contents of the specified clipboard by providing
+ * Virtually sets the contents of the specified clipboard by providing
* a list of supported formats for the clipboard data and a function
* to call to get the actual data when it is requested.
*
* The difference between this function and gtk_clipboard_set_with_data
* is that instead of an generic @user_data pointer, a #GObject is passed
- * in. Because of this,
+ * in.
*
* Return value: %TRUE if setting the clipboard data succeeded. If setting
* the clipboard data failed the provided callback functions
* gtk_clipboard_clear:
* @clipboard: a #GtkClipboard
*
- * Clear the contents of the clipboard. Generally this should only
+ * Clears the contents of the clipboard. Generally this should only
* be called between the time you call gtk_clipboard_set_contents(),
* and when the @clear_func you supplied is called. Otherwise, the
* clipboard may be owned by someone else.
* @len: length of @text, in bytes, or -1, in which case
* the length will be determined with strlen().
*
- * Set the contents of the clipboard to the given UTF-8 string. GTK+ will
+ * Sets the contents of the clipboard to the given UTF-8 string. GTK+ will
* make a copy of the text and take responsibility for responding
* for requests for the text, and for converting the text into
* the requested format.
* @target: an atom representing the form into which the clipboard
* owner should convert the selection.
* @callback: A function to call when the results are received
- * (or the retrieval fails.) If the retrieval fails
+ * (or the retrieval fails). If the retrieval fails
* the length field of @selection_data will be
* negative.
* @user_data: user data to pass to @callback
* the data to be received using the main loop, so events,
* timeouts, etc, may be dispatched during the wait.
*
- * Return value: a newly allocated UTF-8 string which must
+ * Return value: a newly-allocated UTF-8 string which must
* be freed with g_free(), or %NULL if retrieving
* the selection data failed. (This could happen
* for various reasons, in particular if the
* @mask: the transparency mask for an image.
*
* Sets the icon that will be used for drags from a particular widget
- * from a pixmap/mask. GTK+ retains a reference count for the
- * arguments, and will release them when they are no longer needed.
+ * from a pixmap/mask. GTK+ retains references for the arguments, and
+ * will release them when they are no longer needed.
* Use gtk_drag_source_set_icon_pixbuf() instead.
**/
void
* @pixbuf: the #GdkPixbuf for the drag icon
*
* Sets the icon that will be used for drags from a particular widget
- * from a #GdkPixbuf. GTK+ retains a reference count @pixbuf.
- * and will release it when it is no longer needed.
+ * from a #GdkPixbuf. GTK+ retains a reference for @pixbuf and will
+ * release it when it is no longer needed.
**/
void
gtk_drag_source_set_icon_pixbuf (GtkWidget *widget,
g_return_if_fail (GDK_IS_PIXBUF (pixbuf));
site = gtk_object_get_data (GTK_OBJECT (widget), "gtk-site-data");
- g_return_if_fail (site != NULL);
-
+ g_return_if_fail (site != NULL);
gdk_pixbuf_ref (pixbuf);
gtk_drag_source_unset_icon (site);
/**
* gtk_drag_source_set_icon_stock:
* @widget: a #GtkWidget
- * @stock: the ID of the stock icon to use..
+ * @stock: the ID of the stock icon to use
* @size: size at which to render the stock icon
*
- * Sets the icon that will be used for drags from a particular to
- * a stock icon.
+ * Sets the icon that will be used for drags from a particular source
+ * to a stock icon.
**/
void
gtk_drag_source_set_icon_stock (GtkWidget *widget,
}
/**
- * gtk_drag_set_icon_pixbuf:
+ * gtk_drag_set_icon_stock:
* @context: the context for a drag. (This must be called
* with a context for the source side of a drag)
* @stock: the ID of the stock icon to use for the drag.
* @hot_x: the X offset within @pixmap of the hotspot.
* @hot_y: the Y offset within @pixmap of the hotspot.
*
- * Sets @pixmap as the icon for a given drag. GTK+ retains a
- * reference count for the arguments, and will release them when
+ * Sets @pixmap as the icon for a given drag. GTK+ retains
+ * references for the arguments, and will release them when
* they are no longer needed. In general, gtk_drag_set_icon_pixbuf()
* will be more convenient to use.
**/
* @hot_x: The X offset within @widget of the hotspot.
* @hot_y: The Y offset within @widget of the hotspot.
*
- * Changes the default drag icon. GTK+ retains a reference count for the
+ * Changes the default drag icon. GTK+ retains references for the
* arguments, and will release them when they are no longer needed.
* This function is obsolete. The default icon should now be changed
- * via the stock system by changing the stock pixbuf for GTK_STOCK_DND.
+ * via the stock system by changing the stock pixbuf for %GTK_STOCK_DND.
**/
void
gtk_drag_set_default_icon (GdkColormap *colormap,
projects / gtk4.git / commitdiff